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@) Indicating resource utllia^ation in a data processing system. 

@ A graphical system resource monitor Is provided to depict, In real-time, a data processing system's 
internal resource utilization. A window or viewport of a data processing system displays user specified 
internal system resources, such as memory, CPU, or peripheral device availability/utilization. This 
graphical representation of the 'state' of the data processing system's resources Is maintained in 
real-time, while the data processing system's resources Is maintained In real-time, while the Impact on 
the system's performance in providing such Information Is kept to a minimum. This is accomplished 
through a combination of various techniques. Including specialized device drivers for the respective 
devices coupled with a unique data reduction technique. The graphical results of these resource 
monitors are continually updated in real-time. This real-time support provides an Immediate and 
accurate representation of the internal operations of the data processing system. Further, these 
resources can monitored at the process level of a multiprocessing system. These representations can 
be used by a user to identify, isolate, and fine-tune the data processing system's resources to improve 
the overall efficiency of the system being monitored. 
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This invention relates to data processing systems and nnore particularly to a graphical monitor of a data 
processing system's resource utilisation. 

In the quest for continued improvements in efficiency and utilisation of data processing systems, various 
types of data monitors have been developed to aid a user in understanding what is happening 'under the cov- 

5 ers* of these systems. Data processing system resources of interest comprise such things as random access 
memory(RAM) usage, peripheral device usage, and central processing system (CPU) busy/idle time. These 
resources can give an operator of a data processing system key infomnation on fine tuning the various system 
parameters to achieve a higher efficiency of the data processing system's overall throughput. 

Users of operating systems need infonmatton on how much memory is being used. Information on memory 

10 utilisation, especially memory Working Set, is useful for showing if the physical memory in the computer is suf- 
ficient for the currently active applications. Insufflcient memory allocation can cause inefficient system opera- 
tions due to excessive swapping or paging that can occur based on this insufficiency. Prior products analysing 
system memory generally take on the order of 15-45 seconds to execute, depending on the actual amount of 
system memory exists in the system. The information presented is useful for determining the RAM consumed 

15 by an individual application, but only when intrusiveness of the tool, on the system being monitored, Is not a 
factor. These prior products use a text screen. Other previously reported techniques and tools have relied on 
specialised hardware assistance for measuring or calculating RAM usage. 

Other techniques have been used to measure other types of data processing system resources. Direct In- 
temal monitoring, by the system itself, is one technique known to exist. These techniques typically consume 

20 large percentages of the data processing system's own resources in capturing data, and write the captured 
data to some type of mass storage device. Then a subsequent procedure is used to read and analyse this data 
(i.e. analysis not in real time). 

Device utilisation for peripheral devices has historically been measured directly by precisely measuring the 
start-time and complete-time for each I/O (input/output). This allows a calculation of the individual I/O times. 

25 By summing these I/O times over a given period it was possible to calculate total busy time. Then, device util- 
isation is calculated by dividing total busy time by total elapsed time. This approach creates two problenns. First, 
it requires that the entity directly in control of the I/O (usually, either the device hardware and/or operating sys- 
tem) measure and record the I/O start/stop times. Next, it requires a hardware timer with sufficient resolution 
to accurately time these I/O events. On some systems, for example personal computers, neither of these criteria 

30 are met. In other words, the hardware or operating system does not measure I/O time. Further, the hardware 
timer is of such poor resolution (32 milliseconds) in many of today's personal computers that accurate I/O tlnn- 
ings cannot be made. Thus, for existing personal computer systems, device utilisation is not obtainable using 
these conventional methods. 

CPU idle time in a data processing system is the amount of time the computer's Central Processing Unit 

35 (CPU) is not being utilised by any task. Previous methods for measuring CPU idle time used a thread to perform 
a series of tasks. The number of tasks the thread performed was then compared with a hypothetical number 
of tasks that could have been performed, if the thread was allowed all available CPU time. This procedure is 
lacking in that the hypothetical number of tasks is different on different data processing systems. A system spe- 
cific calibration algorithm is required to determine the minimum time the task(s) required to execute. This cal- 

40 ibration method can be unreliable and presents many practical problems when moving between systems. 

In general, the above types of systems are further lacking in that as performance data is gathered, it is 
written by the gathering system to a relatively slow mass storage device for further analysis. This is because 
the methods for capturing the data operate much faster than the methods used to analyse the data. Thus, the 
mass storage device is used as a buffer to allow the methods to operate at different operational speeds. Fur- 

45 thermore, the data generated by the data gathering system is of such a voluminous nature that the analysis 
method is unable to manage or maintain the large quantity of data. This constraint additionally required storage 
to an intenmediate mass storage device. 

As a result of this intermediate buffering, the analysis cannot be performed in real time, but rather is de- 
layed. As such, any reports or other types of feedback of system performance and operation are chronically 

50 out of date with the actual performance. As today's data processing systems are supporting more complex op- 
erating environments, including support for multi-tasking and multi-users, this delay in perfonmance data may 
cause critical system bottlenecks to continue unreported as the cause of any problem may have come and gone 
before being detected. 

Other methods used to analyse the data require a significant amount of the gathering system's resources, 
55 such as the CPU. As a result, the analysis cannot be done In real time, as the analysis consumes such a large 
percentage of the resources, as it would bias the data to not be meaningful of the underiying system operation. 

Some systems have attempted to overcome the above limitations, but in doing so have failed to maintain 
or capture information at a process level of a multiprocessing system. Rather, overall system usage can be 
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monitored, with no ability to focus on a particular process that may be causing the system to be performing 
poorly. This failure of process resolution results in showing that an overall system may be performing poorly, 
but ho meaningful indication of which process in the system is the culprit. 

It is therefore an objeet of the present invention to overcome the above drawbacks of the prior art. 
5 According to the present invention, we provide a method for indicating resource utilisation of a data proc- 

essing system, comprising the steps of: monitoring at least one process of said data processing system by said 
data processing system; generating resource usage data for said at least one process resulting from said mon- 
itoring; and displaying in real time said resource usage data of said data processing system. 

Further, according to the present invention, we provide a system for indicating resource utilisation of a data 
10 processing system, comprising: monitoring at least one process of said data processing system by said data 
processing system; generator means for generating resource usage data for said at least one process resulting 
from said monitoring; and display means for displaying in real time said resource usage data of said data proc- 
essing system. 

The foregoing and other objects, aspects and advantages of the invention will be better understood from 
IS the following preferred embodiment with reference to the figures listed below, in which: 

Figure 1 shows the conceptual model of the system performance monitor. 

Figure 2 shows the functional model of the system performance monitor. 

Figure 3 shows the categories of system memory being monitored. 

Figure 4 depicts the working set calculation timing. 
20 Figure 5 shows the system memory usage algorithmic flow. 

Figure 6 shows a graphical representation of system resources being measured. 
' Figure 7a-7b shows the use. of a viewport menus. 

Figure 8 shows the flow for accepting user input and updating parameters. 

Figure 9 shows how peripheral device utilisation is measured. 
25 Figure 10 shows the construction of a high resolution system timer. 

Figure 11 a-1 1 b shows the fonmat of a generalised record which is stored in the intemal device driver buffer. 

Figure 12 the syntax structure for an application programming interface to a performance data gathering 
control program. 

Figure 13 details the trace pipe records. 
30 Figure 14 shows a data processing system. 

Appendix A-1 thru A-13 is sample C source code for interfacing to the API. 

The following method and system discloses a unique way to monitor a data processing system's resources, 
including RANK utilisation, CPU idle time, and peripheral device utilisation. This monitoring can be performed 
either intemal to the system, or on a remote device attached via conventional communications methods. Va- 

35. nous monitoring and tracing techniques are used for each respective resource being monitored. Data can be 
captured and presented at a process level in a multiprocessing environment. Other types of data processing 
system resources could be similarly monitored, such as data cache, using similar techniques of this invention, 
without departing from the claimed scope of this invention. The overall scheme is integrally packaged in an 
easy to use system, with real-time graphical depiction of resource parameters and support for user-modification 

40 of monitored variables. For purposes of the following discussion, it should be noted that 'real time' is defined 
by Webster's New Collegiate Dictionary to mean 'the actual time in which an event takes place with the reporting 
on or recording of the event practically simultaneous with its occurrence. 

Referring now to Fig. 1, the disclosed monitoring system 21 is conceptually divided into two distinct oper- 
ations, a Data Collection Facility (DCF) 23 and a Resource Monitor (RM) 25. An application programming in- 

45 terface 27, or API, is used as the interface between these two operating models. A named pipe 29, as readily 
known to those of ordinary skill in the art and further described in "IBM OS/2 Programming Tools and Informa- 
tion, Version 1.2" is used to establish the connection between the DCF 23 and RM 25. The DCF 23 collects 
key performance data for various resources 31 being tracked. The RM 25 provides a depiction of resource iis- 
. age. In the preferred embodiment this depiction is displayed graphically on a conventional data processing sys- 

so tem display 33. As a named pipe 29 is used, the system as shown can have the Data Collection Facility 23 
running on a computer distinct from the computer running the Resource Monitor 25, when the systems are con- 
nected via conventional communications techniques. This is because using the named pipe allows for network 
transparent operatk)n. 

Referring now to Figure 2, this system 21 is functionally divided into three sub-categories of operations, 
ss which are data collection techniques 35, data reduction techniques 37, and presentation techniques 39. The 
data collection techniques 35 include RAM working set utilization and sampling of peripheral devices. The data 
reduction techniques 37 include measuring an idle thread to determine CPU idle time, filtering of trace data 
and other reduction methods. Finally, the presentation techniques 39 Include dynamic monitoring and multi- 
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viewport windowing. Figure 2 further illustrates this functional representation being overiayed over the concep- 
tual model of Figure 1 . As can be seen by Figure 2, the data collection techniques 35 are fully contained within 
the Data Collection Facility 23. The data presentation techniques 39 are fully contained within the Resource 
Monitor 25. The data reduction techniques 37 are coexistent in both the Data Collection Facility 23 and the 
5 Resource Monitor 25. As will be subsequently shown, the sharing in responsibility for the data reduction tech- 
niques 37 allows for efficiencies in both data capture and ultimate graphical depiction of the resource being 
monitored. The particular methodologies for each resource being monitored in the preferred embodiment will 
now be described. 

10 RAM UTILISATION 

One of the system resources 31 of Figure 1 which can be nrtonltored Is RAM utilisation. The disclosed mon- 
itoring method quickly (in milliseconds) calculates the memory utilisation for an entire operating system. It dis- 
plays the results graphically In real time. In the preferred embodiment, the operating system is the IBM OS/2 

15 operating system, but these concepts could be readily adapted by one of ordinary skill in the art to any other 
type of computer operating system. 

Referring now to Figure 3, various categories of the total physical memory 41 are defined, with each re- 
spective category's utilisation being graphically depicted. Fixed Memory 43 is memory in a segmented swap- 
ping memory scheme that cannot be swapped out or discarded. It remains allocated in RAM as long as the 

20 application that owns this memory is loaded. Working Set Memory 45 is defined as (i) all the memory segments 
which are not swappable nor discardable, and (11) all the memory segments which are swappable/discardable 
and which are used during the execution of the applicable scenario. Used Memory 47 is RAM allocated by the 
system and present in physical memory (i.e. memory that is allocated and not swapped out). Working Set Mem- 
ory is not an instantaneous value. It is the memory used over a period of time called the "Working Set Period". 

25 The Working Set Period may be dynamically changed, as described in the Dynamic Monitoring section. 

To calculate the Worthing Set Memory 45 of the whole system, an enhanced device driver provides a very 
quick calculation of memory utilisation. It uses a Working Set Period dynamically specified by the user. The 
device driver, which is coded in assembly language and runs at Ring 0 for best performance and uninhibited 
access to protected resources, obtains the Working Set for the whole system, not by session as was previously 

30 done in the prior art Ring 0 will be known to those of ordinary skill in the art to be the ring running at the core 
level of an operating system, or most closest to the CPU hardware. Other levels, such as levels 1 -3 in the pre- 
ferred embodiment operating system of OS/2, run at respectively lower access levels of the CPU's internal re- 
sources. 

In reference to Figure 4. the reported Woridng Set Memory is the percent of memory accessed over the 
35 last "Working Set Period" 51 seconds. It is updated, or snapshots are taken, every "Sampling Period" 53 sec- 
onds. This invention uses a sliding window 55 of memory use to calculate the Working Set Memory. The snap- 
shot of memory taken every Sampling Period examines the Least Recently Used (LRU) timestamps for all mem- 
ory segments (the methods for timestamping will be described later, in the device driver section). The LRU time- 
stamps tell how recentiy a memory segment was accessed. For each snapshot, two values are found: 
40 1 . The latest LRU timestamp for the entire contents of memory. This value Is the last time the most-recently- 

accessed part of memory was accessed. This value is used "Working Set Period" seconds later. 
2. Which segments have been accessed since the LRU time stamp value that was saved "Working Set 
Period" seconds ago. The sum of the size of these segments comprises the Working Set 25 for that time 
period. 

45 The procedure works as follows. The device driver walks through all the physical memory blocks. For each 

swappable, discardable block it does two comparisons: 

1 . Compares the block's LRU timestamp to the LRU timestamp acquired Woricing Set Period seconds ear- 
lier. 

- If the block's timestamp is greater than Working Set Period timestamp, then the block is in the 
so Woricing Set, and the block size is added to the Working Set sum. 

2. Compares the block's LRU timestamp to the maximum (newest) timestamp found thus far; if larger, it 
uses this new value for the current maximum timestamp. 

The device driver returns the maximum (newest) LRU timestamp, the sum of the size (in bytes) of all the 
blocks in the Working Set, and the total physical memory. 
55 This procedure is depicted in more detail in Figure 5. Various variables are initialized at 60. The next block 

of memory Is read by the device driver at 72. The blocksize of menrory being read is added to variable 70 which 
contains the count of Physical Memory at 74. A determination is made on whether the block is free, or unused, 
at 76. If not free, the blocksize is added to tiie variable 66 which contains ttie count of Used Memory at 78. 
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Next, a determination is made on whether the block is swappable/discardable at 80. If not the blocksize is add- 
ed to the variable 68 which contains the count of Fixed Memory at 82. Additionally, since Fixed Memory is de- 
fined to be part of Working Set. the biocksize is also added to the variable 64 which contains the count of Work- 
ing Set memory at 86. If the block is swappable/discardable, processing continues to 84 where a check of the 

5 block's LRU timestamp is made. If the block LRU timestamp is greater than the maximum Working Set Period 
timestamp, the blocksize is added to the variable 64 which contains the count of Working Set memory at 86. 
In either event, the next detemnination is made at 88_on whether the block's LRU timestamp is greater than 
MaxTimestamp 62. If it is greater, the block LRU timestamp is saved as the new MaxTimestamp 62 at 90. Fi- 
nally, a check is made to see if more blocks exist at 92. If so, processing continues at 72. If not, the device 

10 driver returns at 94 the values for MaxTimestamp, Working Set mennory. Used memory, Fbced nrtemory, and 
Physical memory as defined in Figure 3. 

A graphics program, to be later described, invokes the device driver on a periodic basis, plotting the Working 
Set Memory as a percentage of the whole physical RAM in the user's machine. This invocation is achieved by 
the Data Collection Facility communicating via a system API call to the device. Information is then passed to 

IS the graphics program via the API over named pipes 29 of Figure 1 . Referring again to Figure 3, the device driver 
is invoked every Sampling Period 53 to recalculate the Working Set Memory 45 (If the Working Set exceeds 
physical memory, it is displayed as 100%). A typical Sampling Period is 5 seconds and a typical Working Set 
Period is 60 seconds. 

Refenring now to Figure 6, Fixed and Used Memory are graphed as the upper 1 00 and lower 1 02 bounds, 
20 respectively, of the Working Set Memory. Since the Working Set Memory 1 04 is never less than the Fixed Menr>- 
ory nor more than the Used Memory, the graph shows the possible range of the Working Set Memory. This 
feature assists a user In providing a self-calibration mechanism such that the absolute possible minimum and 
maximum values are depicted on the graph automatically. The minimum absolute value is the computed value 
of Fixed memory, and the maximum absolute value is the computed value of Used memory. 
25 For a stable scenario, if the Working Set Period is decreased, the reported Working Set will be lower be- 

cause less memory is typically accessed over shorter periods of time. If the Working Set Period is Increased, 
the Working Set is higher because more merrK>ry for more applications is typically accessed over longer periods 
of time. 

The value of the Working Set Period parameter can affect the reported Woiking Set Memory. Longer per- 
30 iods cause the Working Set Memory to approach Used Memory, or the upper limit. Shorter periods cause Work- 
ing Set Memory to approach Fixed Memory, or the lower limit. Fixed and Used memory are instantaneous val- 
ues. Working Set however, is defined as memory used over a period of time. 

The following Table 1 describes how the RAM monitor can be used to interpret system resources. 

35 
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Table 1 RAM Monitor Scenario Interpretation 



Scenario Interpretation 

Note: The Working Set Period is set to 60 seconds 
for all scenarios. 



A large application 
is loaded. The 
working set shows 
a big increase. The 
£ixed memory shows a 
small increase. The 
user decides not to 
use the application 
for a while, and a 
minute later the 
working set drops back 
down. 



The loaded program is 
reported as part of 
the working set, and its 
fixed memory is reported as 
part of the system fixed 
memory (also included in 
the working set) . For 60 
seconds the memory used 
loading the program continues 
to be reported in the working 
set . 

Because the application is 
not active during the 60 
seconds (and therefore most 
of the application's memory 
is not accessed), the working 
set drops back down after a 
minute even though the 
program is still loaded. The 
application's fixed memory, 
however, is still reported as 
part of the working set and 
as part of fixed memory. 



A large application is This application probably 
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loaded. The working 
set shows a bigger 
increase than expected. 



uses more memory than it will 
during normal operation. The 
reported working set may drop 
later during normal opera- 
tion. 



10 



15 



20 



25 



30 



35 



A large application is 
loaded but then 
immediately ended. 
The reported working 
set rises and falls 
quickly. 

The swap- in and 
swap- out graphs show 
quite a bit of 
activity, even though 
the working set is not 
100% 



When the OS/2 system 
and the SFM 
application first 
start, fixed memory is 
higher than anticipated. 



40 



45 



For a stable scenario, 
the working set period 
is changed from 60 
seconds to 10 seconds. 
The reported working 
set is now lower. 

For a stable scenario, 
the working set period 
is changed from 60 
seconds to 1000 
seconds . The reported 
working set is now 
higher. 



When OS/2 unloads the 
application, OS/2 frees the 
application's memory. Freed 
memory is not reported in 
working set. 



When new segments must be 
swapped in or loaded » old 
segments that have not been 
accessed recently may need to 
be swapped out or discarded. 
The memory swapped out was 
reported in the working set 
if it was last accessed more 
than 60 seconds ago. 

Even with occasional swap 
activity, there may still be 
enough memory for good 
performance. More physical, 
memory is not necessarily 
needed . 

The fixed memory may include 
a large VDISK or DISKCACHE as 
as defined in the CONFIG . SYS 

file. 



The working set is lower 
because less memory is 
typically accessed in 10 
seconds than in 60. 



The working set is higher 
because more memory for more 
applications is typically 
accessed in 1000 seconds than 
in 60 seconds. 



so 



This information on memory utilization, especially the Working Set Memory, Is useful for showing if the 
physical memory in the computer is sufficient for the currentiy active applications. This technique further allows 
55 a user to ask 'what if?' questions without actually resetting the parameters that affect the variable or entity in 
question. In summary, this technique quickly calculates the Random Access Memory (RAM) utilization for an 
operating system as a whole, including the Working Set, Fixed, and Used amounts of RAM and displays these 
results graphically. 
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DYfsiAMIC MONITORING 

The procedure for allowing a data processing systenn user to vary parameters that affect the display of dy- 
namic monitors on a display screen will now be described. This procedure concerns the control of dynamic mon- 

5 itoring of a time-related function on a data processing system display when the function Is affected by at least 
one variable. The data being monitored varies depending upon how certain parameters are set. As shown in 
Figure 7b, a dialogue box is presented to a user on the display screen, which the user has selected from the 
window's menu or action bar 110 as shown in Figure 7a. This dialogue box 120 contains fields 122 in which 
the user can enter new values of the parameters. After the user types in new, or modified, parameters, the pro- 

10 gram dynamically modifies the underlying function to use the new parameter's value. This Is accomplished via 
an API call by the program controlling the dialogue box to the program controlling the data collection. As shown 
in Figure 8, a user parameter Is queried at 1 12 via a dialogue box on the screen of Figure 7b. A check is made 
at 114 to determine If the parameter is valid. If not valid, an error message Is displayed at 116 and the user 
parameter is again queried at 112. If valid, the new parameter is sent via a named pipe (29 of Fig. 1) to the 

15 Data Collection Facility API at 118. The Data Collection Facility accepts data and changes the parameter of 
the specified function at 1 1 9. 

Although the preferred embodiment uses a dialogue box, other types of controls could similarly be used to obtain 
new parameters from a user, such as scroll bars, spin buttons, entry fields or command line parameters. 

This method for varying parameters is used to modify the above-described RAM Working Set Period, the 

20 parameter which affects the dynamic display of the RAM Working Set Memory on the RAM Monitor window. 
As was previously discussed, the RAM Working Set Memory usually becomes lower when the user selects a 
lower RAM Working Set Period, and higher when selects a higher RAM Working Set Period. 

PERIPHERAL DEVICE UTILIZATION 

25 

The general technique used for determining device utilization does not require high-resolution timing or 
changes to the hardware and/or operating system. Rather, this method periodically samples the device's status 
and records the number of times that the device returns a 'device bus/ status. The technique used for gener- 
ating the periodic rate can vary from implementation to implementation, and is not specific or critical to under- 

30 standing the underlying device utilization measurement technique. For example, on a personal computer It is 
convenient to use the hardware timer interrupt, which occurs every 32 milliseconds on an IBM Personal Conrv 
puter running OS/2, and every 55 milliseconds when running DOS. Further, the technique used to query device 
status will vary from device to device, but is similariy extendable to other types of devices without departing 
from the spirit and scope of the present invention. For example, an IBM Personal Computer ESDI disk drive 

35 provides continuous status at input port address x*3512' (hex). Other devices require that a device query com- 
mand be sent to the device before before the device returns status infonmation. 

Referring now to Figure 9, the collection program 140, which is a device driver in the preferred embodiment, 
receives Interrupts 142 from a hardware timer 144. Each timer 'tic' causes the poll count to be incremented at 
146. Then, the device 148 being measured Is queried at 152, through its associated device controller 150 to 

40 determine if the device 148 Is busy or not This busy infonnation is reported at 154 by the device controller 
150. A check is made at 156 to see if the device reported a busy status. If so, the Busy Count is incremented 
at 158, and the collection ends until triggered again by a tic 142. 

Once the collection program has a sufficient numfc>er of samples, as determined by the user specified or 
default parameters, the reporting program 162 then gathers the busy and total counts at 164, and calculates 

45 device utilization at 166 by dividing the busy count by the total count This calculation Is shown as follows: 
Device Utilization = Busy Count / Total Count 
This utilization number can then be reported by any number of methods, such as written to the display at 
168 In either numeric or graphical form as hereinafter described, or written to a log file. This report program 
periodically invokes the collection program device driver, and plots the ratio of the number of busy tics to the 

50 total number of tics 142 as a ratio, in the preferred embodiment The device driver is Invoked every one second 
to recalculate the device utilization, although the frequency of this invocation is user-defined and modifiable 
by the procedures described elsewhere in this preferred embodiment description. 

Because device utilization is being estimated by sampling, rather than measured directiy, there Is potential 
for error in the estimate. Statistical methods can predict tills potential error. As will be readily understood by 

55 those of skill in the art, the sampling technique above uses repeated samples that have only two possible val- 
ues, busy or not busy. Such samples are called Bemouli samples, and follow the Binomial Distribution. Further, 
if tiie number of samples is relatively large, say greater than 20, then the Binomial Distribution may be approxi- 
mated by tiie Normal Distribution. For the Normal Distribution, the error in the sample percentage as compared 
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. to the actual percentage is less than: 

Error = 2(a/2) • (x/n • (1 - x/n) / n) * • 1/2 

where: 

a = Desired confidence level(typically .95 or .99) 
5 Z= Standard random variable for Nonmal Distribution 

X = 'Successful' number of samples (in this case, busy samples) 

n = Total number of samples 

The value for Z(a/2) is found in statistical tables. For a 95 % confidence, Z(a/2) equals 1.960. For a 99% 

confidence, Z(a/2) equals 2.576. 
10 As a specific example, consider that on an IBM Personal Computer running OS/2 a total of 10 « 1/.032 = 

312 samples can be collected in 10 seconds. Further, consider that the largest value that the (x/n * (1-x/n)) 

can attain is .25 when the x is exactly one-half of n (This assertion can be proved by elementary calculus). One 

can then assert with 95% confidence that the maximum error fourid in a ten second device utilization estimate 

does not exceed: 

IS 1.96 » (.25/312) ** 1/2 = .055 = 5.5% 

A similar calculation would show that the maximum error in a one minute sample would be 2.3%. Thus, 
statistics show that the device busy sampling method described above does provide good accuracy in estimat- 
ing device utilization. Further, this method is simpler and less expensive than previous used methods in ob- 
taining device utilization information. 

20 An alternative method of measuring peripheral device utilization is as follows. For measuring logical disl^ 

activity, file system events, which are generated when processes access the file system via an API, are traced 
and reduced by the methods described in the device driver section. 

CPU ACTIVITY 

25 

CPU activity, or utilization, is measured in the preferred embodiment by starting a process and assigning 
the process to the lowest priority level in the system. Rather than tracking the amount of work that the process 
can perform, as was done in the prior art, this invention tracks the amount of time this lowest priority process 
is executing in the system. Since the process only executes when ail other processes at a higher priority have 

30 completed their tasks, and no longer need the CPU, the amount of time the system is idle (or available to perform 
other tasks) is the amount of time the idle process was executing. In the preferred embodiment, data processing 
system tasks are divided into four classes: (i) Time Critical, which Is the highest priority, (ii) Fixed High, which 
mns before any regular task, (ill) Regular, which is the nonmal dass assigned to application programs, and (iv) 
Idle, which means don't run if Time Critical, Fixed High, or Regular priority tasks are ready to execute. 

35 In the preferred embodiment the OS/2 RAS Trace Facility, or SYSTRACE, provided by the OS/2 operating 

system is used to obtain an event trace of this low-level process system activity. This SYSTRACE facility is 
more fully discussed in the device driver section. Other similar types of system tracing facilities provided by 
other operating systems could be used in a similar manner to provide this utility, and not depart from the spirit 
and scope of the present invention. The following describes the specific SYSTRACE utilization. 

40 

DEVICE DRIVER 

In the preferred embodiment, a device driver has been written to perfomn the following SYSTRACE utility. 
The device driver is installed in the normal way, being identified in the CONFIG.SYS file which the data proc^ 

45 essing system reads upon Initial Program Load(IPL). Special groups of instructions, called hooks, are included 
at key points in system and application programs in order to track execution flow. Each hook has a unique iden- 
tity (Major code and Minor code) distinguishing it from all other hooks, and may or may not include key program 
variables, symbols, or return codes as data items. In the preferred embodiment of OS/2, there exists a facility 
known as SYSTRACE which provides means for hooks to be generated, collected, and stored in a buffer. Other 

so operating systems provide similariy functionality through their own system utilities, and this utility can be con- 
sidered as a generic tool for managing hooks. 

The device driver intercepts all hooks passing through SYSTRACE, filters out undesired hooks or infor- 
mation contained therein, and passes only the precise hooks and information desired by the control program. 
The device driver and control program are the two elements comprising the prevk>u8ly discussed Data Collec- 

55 tion Facility. 

Upon device driver installation during system initialization, a 64K buffer is allocated in which data will he 
formatted and passed to the control program. This buffer is internally divided into two 32K buffers, with a portion 
of the second buffer being a communications area for use between the device driver and the control program. 
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The communication area Is simply a portion of data processing system memory reserved for variables. This 
memory is accessible by both the device driver and the application program. The following Table 2 defines the 
variables which occupy the highest (i.e. last) 32 words of the second 32K buffer. 



10 



15 



20 



25 



30 



35 



40 



45 



SO 



time^int 

varAO 

varA2 



egu OFFEOH 
equ OFFEOH 
equ OFFE2H 



st:art:_time equ 0FFE4H 
varBO equ OFFE4H 

varB2 equ OFFE6H 



55 



First DD variable uses OFFEO & 
OFFE2 

One of words used on timetag 
ari throe-tic 

One o£ words used on timetag 
arithmetic 

Second DD variable uses OFFE4 & 
OFFE6 

One of words used on timetag 
arithmetic 

One of words used on timetag 
arithmetic 

elapsed_time equ OFFE8H Third DD variable uses OFFE8 & 

OFFEA 

One of words used on timetag 
arithmetic 

One of words used on timetag 
arithmetic 

Fourth DD: DEKKO FIRST OFFEC 
only 1 word 

Fourth DD: OTHER word for PID 
One of words used on timetag 
arithmetic 

One of words used on timetag 
arithmetic 

if 1, flush hook, otherwise 
process normally 
One of words used on timetag 
arithmetic 

if not O, switch buffers == 
"flush buffers" 
One of words used on timetag 
arithmetic 

accumulates number of real mode 

hooks 

One of words used on timetag 
arithmetic 

One of words used on timetag 

arithmetic 

One of words used on timetag 
arithmetic 

keeps up with nesting depth of 
interrupts 

One of words used on timetag 
arithmetic 

last DD variable uses OFFEC & 
OFFFE 

save previous value 
keep up with high word of time 
approx. 24 bytes effective 



var_FFE8 


equ 


OFFE8H 


var_FFEA 


equ 


OFFEAH 


Dekko_SEL 


equ 


OFFECH 


PID 

var_FFEC 


equ 
equ 


OFFEEH 
OFFECH 


var_FFEE 


equ 


OFFEEH 


flush 


equ 


OFFOH 


var_FFFO 


equ 


OFFOH 


switch 


equ 


OFFF2H 


var_FFF2 


equ 


OFFF2H 


reals 


equ 


OFFF4H 


var_FFF4 


equ 


0FFF4H 


var_FFF6 


equ 


OFFF6H 


var_FFF8 


equ 


OFFF8H 


int_ne sting equ OFF AH 


var_FFFA 


equ 


OFFAH 


current__time equ OFFCI: 


oldtime 
bigtime 
shortbuf 


equ 
equ 
equ 


OFFCH 
OFFEH 
0202OH 
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15 



20 



25 



40 



50 



55 



buffer size is 08000 - shortbuf 
TABLE 2 

Hooking 



Also during this device driver Install, the device driver saves a copy of the original SYSTRACE code located 
10 at the label "strp.common" for future use; A call to the OS/2 system routine DevHelp is used to obtain this ad- 
dress, as shown below: 



SAMPLE ASSEMBLY CODE TO OBTAIN THE LOCATION 

OF "strp_coininon" 

AX: EX POINTS TO THE VARIABLE 

mov al.lOD 

mov dl . DevHlp_GetDOSVar 

call DevHelp 

TABLE 3 



At some later time, the control program executes a "READ" to the device driver at which time the device 
driver installs a patch (modified code) over a portion of the SYSTRACE kemel code. The patch contains bi- 
30 modal (REAL or PROTECT, two differing addressing modes known to those of ordinary skill in the art to be a 
part of the Intel microprocessor architecture) code which can intercept hooks coming through SYSTRACE in 
either REAL or PROTECT mode, and filter out those tasks of interest, and perform other tasks, such as event 
tracing. 

35 Unhooking 

At a still later time, when the system is ready to shutdown, the control program executes a "WRITE" to the 
device driver, at which time the previously saved SYSTRACE kemel code is restored to its original position in 
the SYSTRACE facility, thus fully reinstating the original SYSTRACE function. 



DATA GATHERING 



Event tracing refers to a process of tracing events as they occur in the data processing system. Time stamps 
are associated with each event The events are stored and processed in chronological order. Since the events 
45 are chronologically ordered, the events provide the sequence of activities that take place in the data processing 
system An example of an event trace is shown in the following Table 4. 
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5 



10 



15 





EVENT TRACE EXAMPLE 


Time 0 


Event_0 data 


Time_l 


Events 1 data 


Tiine_2 


Event_2 data 


Time 3 


Ev€nt_3 data 


Time_4 


Event_4 data 


Time_5 


Event_5 data 


Time_n-1 


Event_n-1 data 


Time_n 


Event_n data 



TABLE 4 



20 

The SYSTRACE facility uses the low resolution system clock to place time stamps on events its processes. 
This Is inadequate for the present Invention when attempting to analyze performance on system resources. 
Thus, one of the data processing system's timers is used to determine the delta (difference) times between 
25 events and to replace the time In the SYSTRACE records shown above In Table 3 with a high resolution time 
tag. 

TIMER 

30 The hardware timer of the preferred embodiment is an Intel 8253 timer, which has multiple timers contained 

within. More detailed information on the 8253 timer can be found in the Intel Manual entitled "Intel Component 
Data Catalogue", available from the Intel Literature Dept. in Santa Clara, CA. Timer 0 is programmed to Mode 
2. This mode provides a high resolution timer which starts at OxFFFF and counts downward to OxOOOO and 
repeats. The timer function again begins at OxFFFF, or in other words the timer rolls-over. Tinner 3 is partially 

35 Initialized so that the ordinary interrupt generated by other timers on the 8253 timer module are disabled. Or- 
dinarily, when one of the timer/counters counts down to zero, an interrupt is issued so that the system will know 
that the time being counted has elapsed. In the preferred embodiment of this invention, an interrupt is not de- 
sired at the expiration of the timer/counter, and so this is inhibited by partially initializing Timer 3, also known 
as the watchdog timer (in other possible embodiments, the above timers may be real or they may merely be 

40 emulated by software techniques). The actual time interval being counted is approximately .8380953445 mi- 
croseconds per tic. Referring now to Figure 10, an internal register 180, allocated in system main memory 182 
and initialized to OxOOOO, is incremented each time the interval timer rolls over from OxOOOO to OxFFFF. 
The device driver reads at 1 70 the value firom the internal timer 1 72 of the timer module 1 74. This value is then 
one's-complemented , so that the value effectively ranges from OxOOOO to OxFFFF. This complemented timer 

45 value 176 is combined with the internal register value 178 to provide a 32 bit timer 180 which can count to ap- 
proximately one hour before it rolls over. The high order word 178, which is 16 bits, is the intemal register rollover 
counter, and the low order word 176, also 16 bits, is the complemented timer value. This 32 bit value is known 
as the Time Tag 180, whose use will be described below. 

In order to maintain timing integrity, the above described intemal timer must be read at least once every 

50 55 milliseconds, in order to not miss a rollover. Activating SYSTRACE Major Code 04 will suffice for this re- 
quirement. Major Code 04 tums on or enables interrupts, which includes the timer interrupt. Since each timer 
intemipt occurs every 32 milliseconds in the preferred embodiment, this will guarantee that an event occurs 
(and an associated read of the 8253 timer) at least once every 55 milliseconds. This is because the 8253 timer 
is read every time an event, including an interrupt, occurs. Now that the timer operation is understood, discus- 

55 sion will now turn to when the timer is read. 

Hooks are events that are capable of being monitored, and trigger a particular response in the data proc- 
essing system. An event in OS/2 is usually described by two hooks, a pre-hook and a post-hook. For example, 
when an I/O request is made, the device driver generates a pre-hook signalling the system that a request is 
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about to be made to the I/O adapter. When the adapter completes the I/O. request, the device driver signals 
the completion of the event with a post-hook. The time between the pre- and post-hooks represents the elapse 
time of the event. More specifically, as events occur, such as an I/O request, the kernel servicing the events 
calls the SYSTRACE routine with information describing the event. This allows SYSTRACE to process the 
5 event Each time a hook anrives at the SYSTRACE patch code, meaning that a hook was invoked and that SY- 
STRACE is processing it, the timer is read and the high byte incremented rf necessary(i.e. If the timer rolled 
over, as described above). The hook is examined to see if it is one of the desired hooks. If the received hook 
is one that is being monitored, it is processed further. Otherwise, it is flushed, or continues on with normal proc- 
essing. 

10 If the hook is an interrupt, 04/xx, the device driver measures the time spent processing interrupts. This is 

accomplished by matching the event called "start of an interrupt", called a pre-hook and which is generated 
when an intenrupt handler begins to process the interrupt request, with the event "end of interrupr, called a 
post-hook and which is generated when an interrupt handler completes the processing of an intenrupt request. 
As such, there is a one-to-one conrespondence between pre- and post-hooks, and the timestamps of each are 

15 subtracted from one another to yield the time spent processing the interrupt. 

It is also possible that after a pre-hook occurs, a subsequent pre-hook occurs before a corresponding post- 
hook occurs for the first pre-hook. This nesting of hooks is easily handled in that any post-hook received is 
paired with the most recently received pre-hook. In other words, after one hook starts, another can start, but 
the second will end before the first will end. In this nesting scenario, the end time minus the start time, and 

20 minus all nested activities, is how long the outer event took. 

If the hook is a Mode Switch, 02/xx, the device driver measures the time spent in the REAL mode of the 
CPU by tracking the time from the first mode switch until the scheduler dispatches a different process. This 
time is then subtracted from the time when a mode switch to PROTECT mode occurs. 

If the hook is a Thread Dispatch, 12/01 , the device driver first saves the process identification (PID) and 

25 thread identification (TID) from Its data area (PID and TID is common terminology in OS/2 architected systems; 
the PID is a 16-bit number that uniquely identifies a process within the OS/2 environment. The PID value starts 
at 0001 and increments each time a process is created. TID*s are required as several threads can exist in one 
process). Then, the device driver examines its data to see if it has a PID identical to the PID in the previous 
Thread Dispatch hook 12/01, in which case the hook is flushed. Otherwise, the time spent in Interrupts and the 

30 time spent in REAL mode is appended to the existing Thread Dispatch 12/01 data, which is the PID and TID 
provided by the scheduler describing the event The entire Thread Dispatch hook is reformatted to conform to 
standard PERFMON/DEKOVERT format, as shown in Figure 11a and described later, and written to one of 
the device driver's 32K buffers. The two registers holding the accumulated Interrupt time and the REAL mode 
time are then reset to zero. 

35 If the hook is a FileSystem hook, 30/xx, then the current TID 191 is inserted ahead of the Normal Date, as 

shown in Figure 11b. 

The above listed, and other, hooks of Interest are also reformatted so that they resemble the PERF- 
MON/DEKOVERT format, and written to one of the 32K buffers. The first eight bytes of each record are the 
Major Code 183, the Minor Code 184, the Data Length 185, a Flag 186, and the four byte Time Tag 188, as 

40 shown in Figure 1 1 . The subsequent bytes shown, DDI - DDn at 189 are the hook date. When one of the buffers 
is full, i.e. has used 24K of its 32K space, the buffers are switched using conventional programming techniques, 
and the full 32K buffer is made available to the control program. Data collection continues in the other 32K buffer. 

The device driver also provides for swapping these buffers on a signal from the control program, in order 
to be able to provide the control program with data accumulated up to that point. A similar operation occurs 

45 whenever a TRACE Command is issued, 00/02, hook is received and the first date byte is OxOO (meaning 
that TRACE has been turned off). In this case, it is mandatory that the control program receive the current buffer 
immediately, as there will be no further accumulation of data in either buffer. 

Communication between the control program and the device driver is achieved by using the communication 
area in the respective 32K buffer as follows. In order for the control program to reset the device driver and the 

50 device driver's buffers, the control program loads a control word in the communication area to the value '2', as 
shown in Table 2. When the device driver completes a reset, it changes this a value to *1 '. If the control program 
desires to pause the device driver and buffer filling, the control program loads a control word in the communi- 
cation area to a value of '1*. When the control program desires the device driver to resume, the control program 
loads this control word to a value of '0'. When the control program desires to shut down, or stop, the control 

55 program inhooks the device driver as previously described. Operation is then suspended until such time that 
the control program sends another READ command to the device driver. 
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DATA REDUCTION 

Low-level event trace perfonnance data Is transformed Into high level systenn activities. This Is accomplish- 
ed by the following methodology. First, pre-hook and post-hook events are matched, as previously discussed, 
5 and then these two hooks are transformed into one event. This is because a single record can be used to replace 
the pre- and post-hooks since it is now known how long the event took, and this event timing is the desired 
granularity of information needed. Additionally, as described above, events are filtered to only use information 
In the event records that are of interest to the control program. 

10 APPLICATION PROGRAMMING INTERFACE (API) 

The following describes the application programming interface (API) to the Data Collection Facility. This 
API allows client applications to retrieve perfonmance data and access the Memory Analyzer. 

The API is implemented through two named pipes called the System Pipe and the Trace Pipe. The System 
15 Pipe is used by a client application to send parameters to and receive responses from the Data CoHectlon Fa- 
cility. The Trace Pipe is used by a client application to receive continuous performance data. The Data Collec- 
tion Facility creates both pipes; the client application issues the OS/2 function calls DosOpen and DosCiose 
to access the pipes. Both pipes are created as message pipes in blocking mode (see the "IBM Operating Sys- 
tenn/2 Verston 1.2 Programming Tools and Information" for additional information). 

20 

System Pipe 

A client application controls the actions of the Data Collection Facility through the System Pipe. The client 
application reads from and writes to the pipe in message mode. Each message written to the pipe represents 
25 one parameter from the syntax diagram. A message must be an ASCIIZ string (that is, a null-terminated string, 
or one byte of binary zeros) including numbers (for example, decimal 10 must be sent as the string "10"). 

The Data Collection Facility sends responses back to the client application through the System Pipe. The 
name, used by the client application on the OS/2 function call DosOpen, of the System Pipe in a local machine 
is VPiPBSYSTEM.SPM; on a remote server the name of the pipe is \\server_name\PIPE\SYSTEM.SPM. 
30 Output from the Memory Analyzer (/THESEUS theseus.command) is also sent firom the Data Collection 

Facility to the client application through the System Pipe. First the return codes are sent. Then, output, if any, 
from the Memory Analyzer command is sent. Each message represents a single line from the Memory Analyzer; 
maximum line length is 100 characters. This output is followed by a done message represented by five pound 
signs { MUM ) followed by a null character (00). The System Pipe is disconnected by the Data Collection Facility 
35 when the client application doses the pipe with the OS/2 function call DosCiose. 

Fig. 12 details a syntax diagram for messages that may be sent to the Data Collection Facility through the 
System Pipe. Syntax parameters are explained in Table 5. A parameter is represented as a contiguous set of 
characters. Parameters with uppercase characters are keywords. 

Each parameter must terminate with a null character (binary zero). For example, to send the comment "Per- 
40 formance data for SERVER1" to the SPM application, send the following messages: 



45 



50 



55 
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/COMMENT 

5 

Performance data for SERVERl 



10 



20 



25 



35 



40 



SO 



Table 5 


Data Collection Facility 
Parameters 


Parame-ter 


Aclilon 


/START 


Indicates the types of resources 
about which trace pipe records are 
to be sent by the Data Collection 
Facility. See also Table 8-3. 

* Indicates CPU, physical disk> RAM 
and swap resources when used with 
the /START parameter (does not 
indicate logical disk). Indicates 
all resources when used with the 
/STOP parameter. 

CPU Indicates CPU resources. 

PHySICALDISK 

Indicates physical disk resources. 

LOGICAIJ)ISK 

Indicates logical disk resources. 

RAH Indicates random access memory 
resources. 

SWAP Indicates swapping resources 

Note: All trace pipe records without a 
specific type (designated as "No 
Type" in Table 8-3 are included 
whenever any of the preceding 
options are specified. 


/STOP 


Indicates the types of resources about 
which trace pipe records are not to be 
sent by the Data Collection Facility. 
See option descriptions under /START. 
See also Table 8-3. 


«###« 


Done message. Indicates the end of 
resource specification messages follow- 
ing the /START or /STOP parameter. 
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/COMMENT Imbeds a comment with the collection 

data. 

string Comment to be imbedded in the 
current collection data. 
Comments cannot be longer 
than 40 characters; longer 
comments are truncated to 40 
characters and are accepted 
without error by the Data 
Collection Facility. The 
string must be sent as a 
separate message if it 
contains embedded blanks. 



/EXIT Stops capturing data and releases the 

Data Collection Facility from memory. 
All processes started by the Data 
Collection Facility are also stopped 
( ID££CPU and TBESEUS) . 



/INITDATA Sends initialization records from the 

Data Collection Facility through the 
Trace Pipe. The following records are 
included: 

A Process Info record for the 
IDLECFU process. This is the 
process used by the Data Collec- 
tion Facility to determine the 
time the CPU was idle. This 
process executes at idle priority, 
level O (zero). 

A System Info record. 

A Process Info record for all 
processes currently executing in 
the system. These records are 
only sent if the Memory Analyzer 
has been started ( see the /TBESEUS 
START parameter) . 

Not:e: The CPU resource must be started 
( see the /START CPU parameter in 
Table 8-3) in order to receive 
Process Info records. 



/TOD Specifies the interval (in seconds) 

between Time of Day records sent by the 
Data Collection Facility through the 
Trace Pipe. 
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interval The number of seconds between 
Time of Day records . The 
range of possible values is 1 
to 100 seconds. The default 
is 5 seconds, but the inter- 
val parameter may have been 
set to another value by a 
previous application. 



/RAN Controls the periods used in sampling 

random access memory. See the RAM 
record description in Table 8-3 for 
information about the samples. 

note: This parameter does not imply 
/START RAM. See /START RAM at 
beginning of table for more 
information about enabling the 
RAN resource: 

worlcing_se t_jperi od 

The time frame, in seconds, used 
in determining the amount of 
physical RAM included in the 
working set. Each sample repre- 
sents the amount of RAM used 
during the last working set 
period. The range of possible 
values is 5 to 36O0; the default 
is 60 seconds, but the work- 
ing_set_period parameter may have 
been set to another value by a 
previous application. 

Note: Until a full working 

set period has elapsed, 
the working set 
represents only the 
percentage of RAM in the 
working set since 
Issuing the /RAM parame- 
ter or since the working 
set period was changed. 

saiiiple_interval 

The number of seconds between RAM 
samples. A RAM trace pipe record 
is sent each time a sample is 
taken. The range of possible 
values is 5 to 3 600; the default 
is 10 seconds, but the sam^ 
ple__interval parameter may have 
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been set to another value by a 
previous application . 

Not;e: For performance reasons, the 
SPM application requires that 
the working set period parameter 
value divided by the 
saiiiple__interval parameter value 
be less than or equal to 200. 



/THESEUS Starts the Memory Analyzer if it has 

not already been started by "the Data 
Collection Facility. Provides a 
programming interface to the Memory 
Analyzer from an application. 

Note: The Memory Analyzer full-screen 
interface is not available from 
the copy of the Memory Analyzer 
started by the Data Collection 
Facility in this manner. 

START Causes the Memory Analyzer to 

be started if it has not 
already been started by the 
Data Collection Facility. 

tlieseus^command 

Any Valid Memory Analyzer 
command . The iiheseus^coinniand. 

must be sent as a separate 
message if it contains 
embedded blanks. 

No-te: All the Memory Analyzer commands 
( tlieseus_command ) are 
interpreted directly by the 
Mem ory Analyzer, including the 
THESEUS LOG command. All 
actions will occur from the 
reference point of the Memory 
Analyzer started by the Data 
Collection Facility as though 
they were typed at the Memory 
Analyzer full-screen interface. 

/NOIHESEUS Terminates the' Memory~Analyzer if it 

has been started by the Data Collection 
Facility. This saves the RAM overhead 
associated with the Memory Analyzer on 
the collection machine. However, 
Process Info records for processes 
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/DEBUG 



10 



currently executing in the system 
(excluding the IDLECPU process) are not 
sent through the Trace Pipe. This 
includes processes executing when the 
/INITINFO parameter is sent. 

Indicates that the Data Collection 
Facility is to log parameters it 
receives from client applications to 
the log file SPMLOG.LOG in the working 
directory. 



15 One status message Is sent to the client application by the Data Collection facility for every paranr^eter that 

has a slash (/) as its first character. This status message provides an indication of the success of the request 
from the parameter. The format of a status message is described in the following table. 



20 



25 



1 SPM Return Code 


2 Bytes | 




(Word) 1 


j Service Return Code 


2 Bytes j 




(Word) i 


1 Reserved 


2 Bytes | 




(Word) 1 



30 



35 



Next, the output from any Memory Analyzer commands specified with the /THESEUS parameter (the- 
seus.command) Is sent to the dient application. Each message represent a single line from the Memory Ana- 
lyzer. A done message (#####) follows this output. 

Values that may be returned in the SPM return code field are contained in Table 6. All values are given in 
hexadecimal. 
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Table 6 SPM Return Codes 



5 


Code 


De BC r iptlon 




X 


0000' 


No error, the parameters were accepted. 


10 


X' 


0007' 


Invalid parameter. The service return code 
contains the sequence number of the parame- 
ter that failed. Each parameter beginning 
with a slash (/) will reset the sequence 
number to 1 . 


15 


X' 


0010' 


The working_set_jperiod value is out of range 
(/RAM parameter) . 


20 


X 


0011' 


The saiiiple_interval value is out of range 
(/RAH parameter) . 


X' 


0012' 


The sample__interval value is not a multiple 
working_set_period value (/RAM parameter). 


25 


X' 


0013 ' 


The working_set_jperiod value divided by the 
sa]iiple_interval value is greater than 200 
(/RAH parameter) . 




X' 


0014' 


j.ne / muervax vaxue is ouu oi range. 


30 


X' 


0108' 


Unable to issue the TRACE.EXE ON command to 
the OS/2 system through the OS/2 function 
call DosExecPgm. 


35 


X' 


0208' 


Unable to issue the TRACE.EXE OFF command to 
the OS/2 system through DosExecPgm . 




X' 


0408' 


Unable to start the IDLESPU.EXE program 
through the OS/2 function call 
DosKillProcess . 


40 


X' 


0409' 


Unable to stop the IDDESPU-EXE program 
through the OS/2 function call 
DosKillProcess, 


45 


X' 


0806' 


The Memory Analyzer does not recognize this 
OS/2 version. 




X' 


0807 ' 


Unable to communicate with the Memory 
Analyzer. 


SO 


X' 


0808' 


Unable to start the THESEUS.EXE program 
through the OS/2 function call DosExecPgm. 



55 
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5 


X 


' 0809 


' Unable to stop the THESEUS.EXE program 
DosKi ilProcess . 




V 




' T'Viia r^<*\7"i r"*» Ht"t \r<a» ' I'H h* ^1!!TT^ 5?V'S wafi not Xoad^fi 

from the CONFIG.SYS file. 


10 


X 


1005 


An invalid version of the device driver 

I'HKSkliS JSYS i*ra c: 1^0+" 1 o;^ri^^ f^foiti the 
CONFIG.SYS file. 


15 


X 


'2003 


' The device driver SPMDCF.SYS is missing in 
uiie Cv/NcXCoYo xxie. 




X 


'2004 


Errors occurred while initializing the 
SFHDCF.SYS device driver through DosOpen or 
DosRead. 


20 


Not:er 


The service return code is the return code 
from the requested OS/2 service unless 
otherwise mentioned in this table. 



25 

TRACE PIPE 

The Trace Pipe is used by a client application to retrieve perfomnance data from the Data Collection Facility. 
The Trace Pipe is a one-way named pipe: Data Collection Facility to client application. On a stand-alone ma- 

30 chine, the name of the pipe, as used by the client application on the DosOpen function call, is \PIPE\TRA- 
CE.SPM; on a remote server, the pipe name is \\sorver_namo\PIPBTRACE.SPM. The Trace Pipe is a mes- 
sage stream named pipe (as opposed to a byte stream named pipe) with a maximum message length of 8 kilo- 
bytes. The client application should send a /STOP or /EXIT message on the System Pipe to stop the collection 
and transmission of performance data through the Trace Pipe. 

35 Data Is queued in a buffer by the Data Collection Facility before transmission through the Trace Pipe. Mes- 

sages on the Trace Pipe contain one or more complete trace pipe records. A message is transmitted through 
the pipe at least every 4 seconds, provided data is available. 

The sequence of actions a client application would take to collect performance data from the Data Collection 
Facility is as follows: 

40 1 . Open the System Pipe. 

2. Send appropriate messages to the Data Collection Facility (SPMDCF) through the iSystem Pipe (indud- 
ing the /START message), obtaining retum codes as applicable. 

3. Open the Trace Pipe. 

4. Read data from the Trace Pipe until ready to stop collecting. 

45 5. Send a /STOP or /EXIT message to Data Collection Facility through the System Pipe, obtaining return 

codes as applicable. 
6. Close the System and Trace Pipes. 

TRACE PIPE RECORD FORMAT 

50 

The general format of records sent through the SPM Trace Pipe is: 



Length of Record Trace Pipe Code Variable Length 

Data 

(1 byte) (1 byte) (max. 250 bytes) 



21 
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TRACE PIPE RECORDS 

The records listed in Figs. 13A-C may he sent from the SPM application to a client application through the 
Trace Pipe. 

5 

TABLE DEFINITIONS 
ASCIIZ string 

10 A string of characters followed by a nullcharacter (ASCII 00). Maximum number of characters Is 250. 

data overflow 

Indicates that data has been discarded by the Data Collection facility. Usually this occurs if the client ap- 
15 plication is not reading data from the Trace Pipe quickly enough. 

doubieword 

4 bytes in Intel format (that is, byte/word-reversed). In IBM C/2, this is an unsigned long integer (ULONG). 

20 

elapsed time 

Total timertlcs encountered during the operation. This is not to be interpreted as time the operation was 
busy using the CPU, but rather, the time between when a request was submitted and when the operation com- 
25 pleted. For example, a swap request Is made by the swapper; then the swapper may give up the CPU to another 
process until disk I/O can complete; then the swapper completes the operation. The elapsed time includes the 
entire time. Including the time the swapper was blocked waiting for the disk. 

ID of the first physical disk 

30 

The ID assigned to the first physical disk by the system. Each physical disk is assigned a sequential num- 
ber, beginning with the ID assigned to the first physical disk. 

number of physical disks 

35 

The total number of physical disks installed In the system, 
number of sectors 
40 Number of 512-byte sectors, 

physical disk ID 

The ID assigned to the physical disk. 

45 

process name 

This is the name of the process defined In the .EXE header or the file name of the .EXE file (does not Include 
a period or the file extension). 

so 

time executing previous process 

Total timertlcs encountered while executing the previous process (Includes time spent at Interrupt level 
[time in interrupts previous process]). 

55 

time in interrupts previous process 

Total timertlcs encountered while at Intenrupt level while executing the previous process. 

22 
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time since last Time of Day record 

The elapsed timertics since the last record was sent This value is provided for accurate calculations, 
timertic 

A value derived from the 8253/8254 chip. This value can be converted to microseconds by multiplying the 
value by 0.8380953445; that Is: 

microseconds timertics x 0.8380953445. 

TRACECMD 

indicates that the user issued a trace command, 
word 

2 byes in Intel format (that is, byte-reversed). In IBM CI2, this is an unsigned short integer (USHORT). 
GRAPHICAL PRESENTATION 

In order to graphically depict the resource utilizations or performance monitors described above, the pre- 
ferred embodiment of this invention uses OS/2 Presentation Manager window and graphics functions. This 
method allows a user to view multiple groups of related information in multiple windows (or viewports) simul- 
taneously. One main window, called the parent window, contains all the other windows, called child windows, 
that display resource utilization information. As shown in Figure 6, the resource Information is presented in the 
fomn of graphs which display percentage utilization of a certain data processing system resource. The resource 
utilization data is displayed to represent a user-configurable period of time (e.g. the last 600 seconds), or the 
viewing period 122 of Fig. 7b. Thus, it provides both instantaneous and recent/past records of resource utilh 
zation.A user can choose to view some or alt of the resource monitors, as well as modify the display charac- 
teristics of the windows. Other information, or the same information in other forms, could be presented in the 
child windows. Presentation parameters, which, control how, and when, the data is displayed in the child win- 
dows are changeable by the user from the main window's menu (action) bar. As will be appreciated to those 
of ordinary skill in the art, standard windows programming techniques are used to present the desired graphical 
representation to the OS/2 Presentation Manager interface. The Presentation Manager is the entity that actually 
presents the data in a display window or viewport. Other operating systenns, such as DOS in combination with 
Microsoft's Windows. HP's New Wave, XWindows, or AlXWIndows provide similar programming interfaces to 
a window-like presentations and could similarly be used in the presentation of resource monitors in their re- 
spective systems, without departing from the spirit and scope of the present invention. 

Finally, Figure 14 depicts are generalized data processing system which is the preferred embodiment of 
this invention. A CPU 190, RAM 194, and peripheral device 196 (shown as a direct access storage device, or 
DASD), and interconnected via a bus structure. Similarly, RGB 192 and a keyboard 198 having a pointer/input 
device 200 are attached to this bus 204. These are the resources capable of being monitored in the preferred 
embodiment. Also attached to this bus is a display means 202, capable of rendering the resource monitor's 
results to a user. This display means is similarly attached to the common bus 204. Other variations having high 
speed paths between specific devices, and not a general bus as shown, would similariy fall within the realm of 
this Invention, and would not be a departure from the scope of spirit of the herein claimed invention. 

The present invention has been described for a specific embodiment, but it is equally well applicable to 
other data processing systems where a monitoring of the system resources is useful to the user of the system 
during the execution. 
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r SPM API C Sample Program 

r © Copyright Intemational Business Machines Corporation 1990-1991. 
r All rigMs reserved 

r 

rWHATTHIS PROGRAM DOES: 

r 

r 

r This program opens the SPM System Pipe and uses the SPM 
r API to send commands to the SPM Data Collection Facility. Specifically, 
r the program instructs the Data Collection Facility to report swapping 
r activity. The program then opens and reads records from the Trace Pipe, 
r This program uses the swap records from the Trace Pipe and displays 
r those records on standard output. When the user hits F3, the program 
r instructs the SPM Data Collection Facility to stop sending data, and 
r then the program closes t)oth pipes and exits. 

r WHATTHIS PROGRAM DEMONSTRATES: 

r 

I* This program provides an example of communication with the SPM Data 

/* Collection Fadlity via its Application Programming Interlace (API). 

r The program shows one way to use the SPM System Pipe and Trace Pipes. 

r 

r Include the required sections of the toolkit header files 

^define INCL.DOSFILEMGR 
fdeline iNCL_DOSNMPIPES 
#deflne INCL_DOSERRORS 
#define INCL.KBD 

#pragma pack(1) r IBM CIZ pragma to foroe stmctures onto byte twundaiies */ 
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r Include required header files 7 

I********* **»****t*ttt*t ***************** tj 

include <os2.h> 
include <stdio.h> 
include <stdiib.h> 
include <string:h> 
include 'sampte-h' 
include 'spm2api.h' 



•Global Definitions -V 



SPMDCFREPLYDEFspmdcfRetCodes; r SPM System Pipe return code. V 

r structure */ 

I* Prototype Definitbns 7 

BOOL InitSPMDCF (PIPEDEF*, PIPEDEF*); /* Start communications with SPMDCFV 
BOOL StopSPMDCF (PIPEDEF *, PIPEDEF *); r Stop communications with SPMDCFV 
BOOL ReadTraceData (PIPEDEF*);/* Read performance data V 
USHORT OpenPipe (PIPEDEF*); r Open a named pipe 7 
USHORT ClosePipe (PIPEDEF*); r Close a named pipe 7 
USHORT ReadPipe (PIPEDEF *,UCH/tf^*, USHORT); T Read data from a named pipe 7 
USHORT WritePipe (PIPEDEF *, UCHAR *, USHORT); /* Write data to a named pipe V 

r**** ******** StartofMainProcedure** 



rum. V 

r main calls functions to 1 ) start communicating with the SPM Data 7 

/* Collection Facility, 2) read and interpret data from the SPM 7 

r Trace Pipe, and 3) close communications with the SPM Data 7 

/* Collection FadGty. •/ 

^ 7 

r TraoePipe and SystemPipe are defined and initialized in the header 7 



rfiie 

r 



7 
7 



VOIDcdedmainO 
{ 
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printfCSPM API C Sample ProQram\n"); 

printfj"© Copyright International Business Machines Corp. 1990,1991.\n"); 

printf {"\nPressF3toquit\n\n*); 

printf ("Initiaiizing oommunicab'Dn with SPM Data Collection Facility...\n'); 

r- Instnjct SPM Data Collection Facility to send data ~7 
if (initSPMDCF{&SystemPipe,&TracePipe) l=NO ERROR) { 
^ DosExlt(EXIT_PROCESS, 1); 

printffReading swap data...\n'}; 

/*— Read data and output desired infonnation — */ 
ReadTraoeData(&TraoePipe ); 

printffClosing communications with SPM Data Collection Facility...\n"); 

r- Instruct SPM Data Collection Facility to stop sending data -*l 
SlopSPMDCF{&SystemPipe, &TracePipe); 

printf("Done.\n"); 

} 

I* End of Main Procedure */ 



r InitSPMDCF: 

r Starts communication with the SPM Data Collection Fadiity. 

r Opens System pipe, sends commands to send performance data about 

r swapping activity, and then opens the Trace Pipe. 

r Returns OS/2 sennce return code if an error occurs. 

BOOL InitSPMDCF (PIPEDEF*SystemPipe. PIPEDEFlracePipe) 

SPMDCFREPLYDEF SPMDCFReply; r SPMDCF return codes structureV 
USHQRT rc; 

Appendix A-3 
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r~ Start communication with the SPM Data Colleclion Facility by 7 
r— opening the System Pipe. */ 
if ((rc = OpenPipe (SystemPipe)) != NOJRROR) { 

fprintf(sluen; "Error opening system pipe: rc= %d\n", rc); 

return rc; 

1 

r- Instruct the SPM Data Collection Facility to send records V 
I*— over the trace pipe when swapping is detected. 7 
if ((rc = WritePipe (SystemPipe, '/START SWAP, 0)) 1= NOJRROR) ( 

|printf(stderr, 'Bror writing to system pipe: rc = %d\n', rc); 

retum rc; 

1 

/*- Tell SPM Data Collection Facility that tWs message is complete. 7 
if ((rc= WritePipe (SystemPipe 

,PIPE_MSG_DONE 

.PIPE MSG_DONE LEN) 
)!= NOJRROR) { " 

fprintf(stden; 'Error writing to system pipe: rc ~ %d\n', rc) ; 
retum rc; 

} 

r- Read and check the response from the SPM Data Colleclion Facility 7 
« ((rc "jjQ^£p^j|y^*®"^^^^ *• aSPMDCFReply, sizeof(SPMDCFReply)) 

fprintf(stden; 'Enror reading from system pipe: rc - %d\n', rc); 
retum rc; 

) 

if (SPMDCFRepiy.SPMRetCode!=SPMNOERROR) { 

4)rintf(stderr, 'Error from SPMDCF: SPM letum code = %d\n', 

SPMDCFRep|y.SPMRetCode); 
fprintf(stden; ■ service return code =%d\n", 

SPMDCFRep!y.ServiceRetCode); 
fprintf(stden; ' service category =%d\n", 

SPMDCFReply.SPMRetCode); 
retum SPMDCFReply. SPMRetCode; 
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r- Open the trace pipe in order to read data from SPMDCF V 
if ((rc=OpenPipe(TracePipe))!=NOJRROR) { 

fprintl(stden; 'Error opening traoe pipe: rc = %d\n', fc); 

return Fc; 

} 

return NOJRROR; 



r ReadTraceData 

r This function monitors the Traoe Pipe for records indicating 
r that swapping tooi^ place, if such a record is read from the Trace 
r Pipe, it is printed. FuncHon terminates when F3 is pressed. 

BOOL ReadTraceData (PIPEDEF*TracePipe) 

static UCHAR spmBuffer{MAX_SPMDCF_MSG_SIZE]; r txiffer for trace data V 

static UCHAR *spmBufferPtn r place holder in trace tHjffer V 

static USHORT bufferContentsSize, bytesScanned; 

SPMTRACERECS*spmRecord; r pointer to record in buffer V 

static USHORT pipeHandle; r local storage of named pipe file handle V 

static USHORT rc; » 

static BOOL done; 

KBDKEYINFO KBDKey; 

HKBD KBDHandiesO; 

pipeHandle = TracePipe -> Handle; /* local storage (better performance) V 

KBDKey.chScan=0; T Until the F3 key Is pressed */ 

done = FALSE; 

do{ 
do{ 

/*- Read data from the frace pipe; INs call wiO block until 

I*— dsts is rDC6iv6d 

r- If ERROR_MORE_DATA, then read a new buffer in. 
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/*- ERROR_MORE_DATA is not expected and only occurs in veiy V 
/*— unusual circumstances. 7 

rcs DosRead (pipeHandle 



if (rc = ERROR_MORE^DATA){ 
^Mintflstderr, "Enor reading trace pipe: ERROR_MORE_DATA\n'); 

} while (rc=ERROR_MORE^DATA); 
/*-- check for enors*/ 

if ((rc!=NO_ERROR)||(l)ufferContentsSize=0)){ 
$rintf(stden; 'Error: tiroken trace pipe communication.\n"); 
return FALSE; 

)/*endif*/ 

/*- set trace buffer pointer to point to cunent trace buffer V 
spmBufferRr^spmBuffer; 

/*- set trace record pointer to point to current record in buffer * 
spmReoord = (SPMTRACERECS *) spmBufferRn 

/*— scan the buffer for the trace records we want 7 
for ( bytesScanned^O; \ 
bytesScanned<bufferContentsSize; \ 



spmBufferPb- +=spmRecord->Recl^n, \ 
bytesScanned +- spmReoord->Recl^n) 

spmRecord = (SPMTRACERECS *) spmBufferPtr; 

/*- Check for spurious trace record lengths 7 

/*— This error should never happen under nomial conditions. 7 



,spmBuf[er 
,MAX_SPMDCF_MSG_SIZE 
,&bufferContentsSize); 
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if (spmRecord->RecLen = 0){ 
fprintf(stderr, 'Error: invalid trace record length = 0\n"); 
return FALSE; 

1 

r- Interpret wtiat kind of record it is and compile stats */ 
switch (spmReGord->Code) ( 

r— in this sanfie program, we seek only Swap records —V 

/*- Swap In record-*/ 
case SWAPINCODE: 

printf ("Swap In: elapsed time: %lu timertics, 

spmRecord->0ata.8wap.ElapsedTime); 
printf {"%lu microseconds, 

(ULONG) (0.8380953445 * spmRecord->Data.Swap.EiapsedTime)); 

printf fbytes: %lu\n', spmRecord->Data.Swap.Bytes); 
break; 

/*- Swap Out record-*/ 
case SWAPOUTCODE 

printf ("Swap Out: elapsed time: %lu timertics, 
spmRecord->Data.Swap.Eiapsed7ime); 
printf (^olu microseconds, 

(ULONG) (0.8380953445 * spmRecord->Data.Swap.Elapsed7]me)); 

rintf ("bytes: %lu\n", spmReoord->Data.Swap.Bytes); 
reak; 

default: 

r ignore this record*/ 

break; 
J /* end switch*/ 
/* end for*/ 
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f*— chsck if us6r wsnts to ouit (F3 ksy) */ 

KbdCharin (&KBDKey, (USHORT) 1, KBDHandle); r donlwait for keystroke V 

if (KBDKey.cf)Scan=r0x3D} ( 

^ donerTRUE; /*F3 key pressed 7 

1 wiiile ((rc» NO.ERROR) && (done ^ FALSE)); 
return TRUE; 



r StopSPMDCF: 

I* Instructs tfie SPM Data Collection Facility to stop sending 

r performance data over the Trace Pipe. Then cbses the Trace and 

I* System Pipes. 

BOa StopSPMDCF (PIPEDEF*SystemPipe,PIPEDEF7raoePipe) 

SPMDCFREPLYDEF SPMDCFRepiy; 
USHORT rc; 

/*- Instmct the SPM Data Collection Facility to stop sending records V 
if ((rc=WritePipe(SystemPipe,VSTOP",0)) l« NO.ERROR) | 

^rintf(stderr, 'Error writing to system pipe: rc = %din*,rc); 

return rc; 

1 

r-^ Tell SPM Data Collection Fadiity that this message is complete. V 
if ((rc- WritePipe (SystemRpe 

.PIPE_MSG_DONE 

.PIPE_MSG_DONE,LEN) 
) !=NO_ERROR)| 

^rintf(stden; 'Error writing to system pipe: rc = %d\n',rc); 
return rc; 

} 

Appendix A-8 
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/*- Read and check the response from the SPM Data Colleclion Facility */ 
if ((rc = ReadPipe (SystemPipe, (VOID *) &SPiy!DCFReply, sizeof (SPI\/IDCFReply)) 
) bNO_ERROR)( 

lpfintf(stdin; "Error reading from system pipe: rc = %d\n", rc); 
return rc; 

If {SPMDCFReply.SPMRetCode!=SPMNOERROR) { 
4)rinlf(stderr, "Error from SPMDCF: SPM retum code =%d\n*, 

SPMDCFReply.SPMRetCode); 
tprinlf {stden; ' service return code = %d\n", 

SPMDCFReply.ServiceRetCode); 
fprintflslderr," service category =%d\n*, 

SPl\4DCFRepiy.SPMRetCode); 
retum SPMDCFReply.SPMRetCode); 



/*— Close the trace pipe V 

if ((rc=Ck)sePlpe(TraoePipe)) !=N0_ERROR) { 

^)rintf(stderr, "Error dosing trace pipe: rc = %d\n",rc); 

return rc; 

} 

r— Close the system pipe */ 

if ({rc =ClosePipe (SystemPipe)) l=NO_ERROR) { 

^rintf(stderr, 'Error dosing system pipe: rc = %d\n",rc); 

retum rc; 



retum NO_ERROR; 
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I* * * * * * * * » * * t * * t t t t t * * • It t * * t t * * t t * * t t * t * t 

/* OpenPipe: 

f Attempts to open the pipe indicated by the parameter Pipe. If the 
r pipe is busy, this procedure waits until it beooms free, then 
I* tries to open the pipe again. If the pipe is again twsy, then a 
r return code of ERROR_PIPE_BUSY is returned. If any other em)r 
r occurs, then the DosOpen return code is returned. 

^ t « * « * « 1 1 • 1 1 1 1 • • t • * * * * ft « « * * « « * * * * * t * * * * * 

USHORTOpenPipe{PIPEDEF 'Pipe) 

USHORT RetCode; 
USHORT ActionTaken; 
USHORT OpenMode; 
BOOL TriedOnce; 

/*— Don't open the pipe if it's already open */ 
if {Pipe->lsOpen=TRUE) | 

retum(NO_ERROR); 
} rendifV 

TriedOnce = FALSE; 
RetCode = NOJRROR; 

/*— Set the correct file mode for the named pipe we are about to open */ 
if {PIPE->OpenMode & DUPLEX.PIPE) ( 
/*- System Pipe V 

OpenMode = (BASE OPEN_MODE | READ_WRITE); 
) else if {Pipe->OpenMbde and OUT BOUND_PIPE) { 
/*— Trace pipe V 

OpenMode =(BASE_OPEN_iyiODE | READ ONLY); 



do ( 

r~ Attempt to open the pipe V 
RetCode = DosC)pen{pipe->Name, 

&(Pipe->Handle), 
&ActionTaken, 
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OL, 

0x0000, r FileAttribute V 
0x0011, r OpenFlag = Create or Open */ 
OpenMode, TOpenMode */ 
OL): r Reserved V 

r-lf we've tried twice and we get an error return code, then return 7 
/*— the error return code. */ 
if ((TriedOnce) && (RetCode != NO JRROR)) ( 

retum(RetCode}; 
) else I 

/*— act on the return code V 
switch (RetCode) ( 

caseNO_ERROR: 
Rpe->lsOpen = TRUE; r Set flag that pipe is open V 

r~Make sure that the named pipe is in the slate that we want V 
RetCode = DosSetNmPHandState{Pipe->Handle, 

READ^WRITE BLOCK I READ PIPE AS MSG 
); ~ I - - - 

retum(RetCode); 
break; 

case ERROR_PIPE_BUSY: 
r~Wait until the named pipe is free or until time's up V 
DosWaitNmPipe(Pipe->Name, Pipe->BusyWiait); 
break; 

default: 

/*~An error occurred, so retum the return code from the DosOpen 7 

retum{RetCode); 
break; 
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) /* endswitcti */ 

} /* endeise first time DosOpen was tried, or no error V 

TriedOnce = TRUE; /* set flag to show we tried and failed*/ 

} while {RetCode != NO.ERROR); /* enddo */ 
return RetCode; 



r ClosePipe: */ 
r Cbses the pipe indicated by the parameter and retums the DosCbse V 
/* letum code. Sets the pipe state in the Pipe structure. V 

USHORTCIosePipe{PIPEDEF 'Pipe) { 
USHORT RetCode; 

RetCode = Do5Ciose(Rpe->Handle); 

if (RetCode ==NO_ERROR){ 

Pipe->lsOpen= FALSE; 
} r endif V 

retuni(RetCode); 

} 
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r WritePipe: 

r Writes data to the pipe indicated by the parameter Pipe. The data 
r is stored in Buffer, and the length of the data in Bulen. If the 
/* data is an ASCIIZ string, then setting Bulen to zero will cause 
r WritePipe to calculate the length of the string. 

/* The DosWrite return code is returned with the exception that If 
r less data was written than in the data buffer, ERROR_MORE_DATA is 
r returned. If a DosWrite error oocurs, the number of bytes written 
r is reset to zero. 

r 

USHORT WritePipe{PIPEDEF *Pipe, UCHAR *Buffer, USHORT BufLen) 

USHORTRetCode; 
USHORT DataLen; 

r— calculate the length of the buffer if not specified V 
if (Buflen»0){ 

DataLen = strten(Buffer) + 1 ; /* AsdiZ string V 
} else { 

DataLen = BufLen; 
} r end else *l 

r-write the data to the pipe V 

RetCode = DosWrite(Rpe->Handle, Buffer, DataLen, &{Pipe->BylesWritten)); 

/*— chedi that the write succeeded V 
H (RetCode !=NO_ERROR) { 

Pipe->BytesWritten = 0; 
} else if (Pipe->BytesWritten< DataLen) { 
, RetCode = ERROR MORE DATA; T- not all the data was written */ 
} r endif V 

retum RetCode; 

) 
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r ******** * * */ 

r ReadPipe: * 

/* Reads the pipe indicated by the parameter. The data is read from * 

/* the pipe into the spediied tnjffer, and the length of the data * 

r is returned in the Pipe structure. BufLen indicates the size of the */ 

r data buffer. */ 

/* Returns the DosClose return code. Sets number of bytes read to */ 

/* zero if an error occurs. */ 



USHORTReadPipe{PIPEDEF *Pipe. UCHAR *Buffer, USHORT BufLen) 
USHORTRetCode; 

RetCode = DosRead(Pipe->Handle, Buffer, Buien, &(Pipe->BytesRead)); 

if(RetCode !=N0_ERROR) { 
Rpe->BytesRead = 0; 



. return RetCode; 



r ******* * SAMPLE C Sample Program Header file (.H) * * * 

r The SAMPLE header file defines symboGc constants used 
Tin the SAMPLEC file. 

r SAMPLE local procedure dedarations may appear in this file to 
r ensure they have been declared before being used. 

r ©Copyright International Business Machines Coiporation 1990, 1991 
r Ail rights reserved 

r 



Appendix A-14 



37 



0S18574A2J_> 



EP 0 518 574 A2 



r Open Modes for DosCreateNmPipe V 
Adeline PRIVATE_HANDLE 0x0080 
^define DELAYED WRITE NOT ALLOWED 0x4000 
#deflneDELAYEDlWRrrE"ALLOWED 0x0000 
#defineDUPLEX_PIPE 0x0002 
«defineOUT BOUND PIPE 0x0001 



r Open Modes for DosOpen V 

#defineBASE_OPEN_MODE 

#defineREAD_WRrrE 

#defineWRITE_ONLY 

#delineREAD_ONLY 

r Rpe Mode for DosMakeNmPipe V 

#defineREAD WRITE BLOCK 

V " " 

#define READ.WRITE.NOJLOCK 

#defineBYTE_STREAM 

#defineMESSAGE_STREAM 

#defineREAD_PIPE_AS_BYTE 

#defineREAD_PIPE_AS_MSG 

#defineSINGLE INSTANCE PIPE 



0x20C0 V 
0x0002 */ 
0x0001 
0x0000 



000011000000 V 
0010 V 



0x0000 7 Wait for data on read/write requests 

0x8000 
0x0000 
0x0400 
0x0000 
0x0100 
0x0001 



r Structures and type definitions 

r The PIPEDEF structure iiolds information related to a pipe V 
typedef struct _PIPEDEF { 

USHORT BytesWrilten, BytesRead, Handle, RelCode; 
USHORT IsOpen, OpenMode, PipeMode; 
USHORT InSize, Outsize; 
ULONG BusyWait; 
UCHAR Name[80J; 
UCHAR •Buffer; 
} PIPEDEF; 
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PIPEDEF SystemPipe= { 

r SPM System Pipe (Communicalion between SPMDCF and Application) */ 



0,0.0,0, FALSE, 
{PRIVATE HANDLE 
DELAYED_WRITE NOT ALLOWED 
DUPLEX PIPE 
(READ WRITE_BLXK 
MESSAGE_STREAM 
READ_PIPE_AS_MSG 
SINGLEJNSTANCE PIPE 
256, 
128, 
5000L, 

"\\Pipe\\System.SPM*, 
NUa}; 



/•Runtime status fields */ 

/* Open Mode V 

), /* Receive and send data V 

/* Pipe Mode */ 



r Output Buffer Size */ 

/* Input Buffer Size V 

r Wait ms if busy pipe V 

/* Name of tlie pipe V 

/* Pointer to Pipe Buffer V 



PIPEDEF TraoePipe = ( 

r SPM Trace Pipe (trace records sent from SPMDCF to application) V 



0,0,0,0, FALSE, 

(PRIVATE HANDLE | 
DELAYED WRITE NOT ALLOWED 
OUT.BOUND_PIPE " ) 
(READ.WRITEJLOCK 
MESSAGE_STREAM 
READ_PIPE_AS_MSG 
SINGLEJNSTANCE PIPE 
65535, 
0, 

5000L, 

■\\Pipe\\Trace.SPM*. 
NUa); 



Run time status fields 
/* Open Mode 



/* Pipe Mode 



r Output Buffer Size 
/* Input Buffer Size 
/* Wait ms if busy pipe 
r Name of the pipe 
r Pointer to Pipe Buffer 



1 
7 
V 

V 
V 



V 
7 
V 
7 
7 
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Claims 

1. A method for indicating resource utilization of a data processing system, comprising the steps of: 
monitoring at least one process of said data processing system by said data processing system; 
generating resource usage data for said at least one process resulting from said monitoring; and 
displaying in real time said resource usage data of said data processing system. 

2. The method of claim 1 wherein said at least one resource is random access memory. 

3. The method of claim 1 wherein said at least one resource is peripheral device. 

4. The method of claim 3 wherein sail peripheral device is any of direct access storage device or communi- 
cation adapter. 

5. The method of claim 1 wherein sail step of displaying in real time said resource usage data is displayed 
on a data processing system display. 

6. The method of Claim 5 wherein said resource usage data is displayed in windows of said data processing 
system display. 

20 7. The method of Claim 5 wherein sail resource usage data is displayed on a local data processing system 
display. 

8. The method of Claim 5 wherein said resource usage data is displayed on a remote data processing system 
display. 
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9. The method of Claim 1 wherein said step of monitoring is partially performed by a device driver. 

10. The method of Claim 1 wherein said step of monitoring is substantially perfomfied by a device driver in 
tandem with a control program. 

11. A system for indicating resource utilization of a data processing system, comprising: 

monitor means for monitoring at least one process of said data processing system by said data proc- 
essing system; 

generator means for generating resource usage data for said at least one process resulting from 
said monitoring; and 

display means for displaying in real time said resource usage data of said data processing system. 

12. The system of claim 1 1 wherein said at least one resource is random access memory. 

13. The system of daim 1 1 wherein said at least one resource is peripheral device. 
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THE GENERAL FORM OF A NORMALIZED RECORD: 
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SPM/2 Trace Pipe Records 
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SPM/2 Trace Pipe Records 
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